Feat/added option to specify custom command description as array#1982
Feat/added option to specify custom command description as array#1982Benni0 wants to merge 4 commits intosplunk:developfrom
Conversation
…tion for custom command arguments.
kkedziak-splunk
left a comment
kkedziak-splunk
left a comment
There was a problem hiding this comment.
Review Summary
This PR adds support for specifying the command description as an array of strings (for better JSON readability) in addition to the existing single-string format. The multiline description is joined with \\\n for searchbnf.conf and with \n for Python docstrings.
Issues found:
-
Join separator uses backslash-newline (
create_searchbnf_conf.py):" \\\n".join(description)produces a backslash continuation in the.conffile. This works forsearchbnf.conf, but it is worth verifying that Splunk's conf parser handles backslash line continuations correctly in description values. If not, consider joining with a single space instead. -
Python docstring join (
create_custom_command_python.py):"\n ".join(description)joins with newline + 4 spaces indentation. This assumes the docstring context always has 4-space indentation. The template itself might have different indentation — verify this is consistent. -
descriptiontype changed in schema but not in all validators: The schema now usesoneOf: [string, array[string]]fordescription, which is good. But the_validate_custom_search_commandsinglobal_config_validator.pystill usescommand.get("description")— this works for both types (truthy check) so it's fine. Just noting that the error message on the validation failure path still says"One of the attributes among description, usage, syntax"from the stacked PRs. -
No validation for empty strings in array: The schema allows
{"type": "array", "items": {"type": "string"}}withoutminLengthon items orminItemson the array. An empty array[]or array with empty strings[""]would pass schema validation but produce empty/broken descriptions. -
Doc table type column: The type is shown as
string or array[string]— consider usingstring \| array[string]or similar markdown-friendly formatting for clarity in the rendered table.
Overall a clean feature addition with good test coverage (both conf file output and Python file output).
| syntax_lines[-1] += f" {part}" | ||
| else: | ||
| syntax_lines.append(part) | ||
| syntax = " \\\n".join(syntax_lines) |
There was a problem hiding this comment.
The join separator " \\\n" produces backslash line continuations in the .conf file. Worth verifying Splunk's conf parser handles backslash continuations correctly in description values of searchbnf.conf. If not, joining with a single space might be safer.
|
|
||
| description = command.get("description") | ||
| if description and isinstance(description, list): | ||
| description = "\n ".join(description) |
There was a problem hiding this comment.
The join separator "\n " (newline + 4 spaces) assumes the docstring context always has 4-space indentation. Verify this is consistent with the template's indentation.
| "oneOf": [ | ||
| { | ||
| "type": "string" | ||
| }, |
There was a problem hiding this comment.
The oneOf allows an array with no minItems and string items with no minLength. An empty array [] or [""] would pass validation but produce an empty or near-empty description. Consider adding minItems: 1 and/or minLength: 1 on the string items.
2 participants
PR Type
What kind of change does this PR introduce?
Summary
Added the possibility to define the description of a custom command as an array of strings, to improve the readability of long comprehensive descriptions in json format. Each string will result in a single line of searchbnf.conf or within the description of the command python.
Changes
Modification of the json schema to allow a string array as description and modified the searchbnf.conf generator and the custom command python generator to format the description accordingly.
This is another update after #1977, #1979 and #1980.
User experience
It is now possible to split long descriptions in multiple lines, which improves the readability in
globalConfig.json.Checklist
If an item doesn't apply to your changes, leave it unchecked.
Review
Tests
See the testing doc.
Demo/meeting:
Reviewers are encouraged to request meetings or demos if any part of the change is unclear